IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/libstiff.z/libstiff

Text File | 2002-10-03 | 20.1 KB | 550 lines

LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



LLLLIIIIBBBBRRRRAAAARRRRYYYY DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_b_s_t_i_f_f provides a C Language application programming interface (API)
     for the reading and writing of Stream TIFF files. Stream TIFF (STIFF) is
     a subset of the Tag Image File Format (TIFF) originally developed by
     Aldus Corporation. The TIFF file format is an extremely flexible format
     well suited for monochrome and color bitmap images. The difference
     between TIFF and STIFF is that while a TIFF file may require file seeking
     during reading or writing a STIFF file does not. This means that a STIFF
     file can be read from and written to non-seekable streams such as pipes
     and sockets. It is important to note that a STIFF file may be read by any
     TIFF reader that conforms to the TIFF Revision 6.0 specification.
     However, the _l_i_b_s_t_i_f_f API should not be used to read standard TIFF files.

     The functions provided by _l_i_b_s_t_i_f_f greatly simplify the reading and
     writing of TIFF compatible files. Using the STIFF API, TIFF compatible
     files can be read and written without the need to understand the
     structure of a TIFF file and without the need to explicitly specify TIFF
     tags.

LLLLIIIIBBBBRRRRAAAARRRRYYYY AAAACCCCCCCCEEEESSSSSSSS
     There are two sets of _l_i_b_s_t_i_f_f functions. One set comprises the generic
     _l_i_b_s_t_i_f_f API. These functions are designated by an SSSSTTTT prefix. These
     functions may be used to read and write generic STIFF files.  To access
     these functions an application must include the header file _s_t_i_f_f._h
     located in the /_u_s_r/_i_n_c_l_u_d_e directory. The second set of _l_i_b_s_t_i_f_f
     functions are a subset of the generic functions and are tailored to
     reading and writing STIFF files that are to be passed between printing
     filters and drivers. These printing related functions are designated by
     the prefix PPPPSSSSTTTT and are accessed through the header file _p_r_i_n_t_s_t_i_f_f._h also
     located in /_u_s_r/_i_n_c_l_u_d_e.  If _p_r_i_n_t_s_t_i_f_f._h is used, the header _s_t_i_f_f._h
     need not be specified.  The generic and printing specific functions may
     be freely intermixed within an application. All _l_i_b_s_t_i_f_f functions
     require that the _s_t_d_i_o._h file be included.

     Programs that call _l_i_b_s_t_i_f_f functions must link with the _l_i_b_s_t_i_f_f._a
     library located in the directory /_u_s_r/_l_i_b.

FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
   GGGGeeeennnneeeerrrriiiicccc FFFFuuuunnnnccccttttiiiioooonnnnssss
     SSSSttttrrrreeeeaaaammmm HHHHaaaannnnddddlllliiiinnnngggg
               STOpen
               STClose
               STSkipTo

     RRRReeeeaaaaddddiiiinnnngggg aaaannnndddd WWWWrrrriiiittttiiiinnnngggg
               STReadImageHeader
               STWriteImageHeader
               STRead
               STWrite






                                                                        PPPPaaaaggggeeee 1111






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



     TTTTIIIIFFFFFFFF TTTTaaaagggg SSSSuuuuppppppppoooorrrrtttt
               STAddTag
               STRemoveTag
               STGetTag
               STPrintTags

     EEEExxxxeeeeccccuuuuttttiiiioooonnnn EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
               STPerror
               STErrorString

   PPPPrrrriiiinnnnttttiiiinnnngggg SSSSppppeeeecccciiiiffffiiiicccc FFFFuuuunnnnccccttttiiiioooonnnnssss
     RRRReeeeaaaaddddiiiinnnngggg aaaannnndddd WWWWrrrriiiittttiiiinnnngggg
               PSTReadImageHeader
               PSTWriteImageHeader

UUUUSSSSIIIINNNNGGGG TTTTHHHHEEEE LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
   WWWWrrrriiiittttiiiinnnngggg AAAA SSSSTTTTIIIIFFFFFFFF FFFFiiiilllleeee
     The typical sequence of operations for writing a STIFF file is as
     follows:

     1.   Obtain a writable file descriptor. Note that this descriptor can be
          associated with a non-seekable stream.

     2.   Call _S_T_O_p_e_n with the writable file descriptor and the flag SSSSTTTT____WWWWRRRRIIIITTTTEEEE.

     3.   Fill in the STIFF image header (_S_T_I_m_a_g_e_H_e_a_d_e_r or _P_S_T_I_m_a_g_e_H_e_a_d_e_r).

     4.   Optionally, add any application specific TIFF tags to the file using
          _S_T_A_d_d_T_a_g.

     5.   Call the image header write function _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r.

     6.   Write the image data using _S_T_W_r_i_t_e.

     7.   Repeat steps 3 through 6 for each page of image data.

     8.   Close the STIFF stream using _S_T_C_l_o_s_e.

     9.   Close the file descriptor.

   RRRReeeeaaaaddddiiiinnnngggg AAAA SSSSTTTTIIIIFFFFFFFF FFFFiiiilllleeee
     The typical sequence of operations for reading a STIFF file is as
     follows:

     1.   Obtain a readable file descriptor. Note that this descriptor can be
          associated with a non-seekable stream.

     2.   Call _S_T_O_p_e_n with the readable file descriptor and the flag SSSSTTTT____RRRREEEEAAAADDDD.

     3.   Call the image header read function _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r or
          _P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r.




                                                                        PPPPaaaaggggeeee 2222






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



     4.   Access the fields of the image header structure to determine the
          amount of image data to be read for this page.

     5.   Optionally, obtain the values for any application specific TIFF tags
          from the file using _S_T_G_e_t_T_a_g.

     6.   Read the image data using _S_T_R_e_a_d.

     7.   Repeat steps 3 through 6 for each page of image data.  The last page
          of image data will either have its _l_a_s_t image header field set to
          one or will be an empty page (i.e. amount of data equals zero).

     8.   Close the STIFF stream using _S_T_C_l_o_s_e.

     9.   Close the file descriptor.

     If an error condition is returned by a _l_i_b_s_t_i_f_f function, _S_T_P_e_r_r_o_r can be
     used to print a diagnostic error message to the standard error.

GGGGEEEENNNNEEEERRRRIIIICCCC SSSSTTTTIIIIFFFFFFFF FFFFIIIILLLLEEEE SSSSTTTTRRRRUUUUCCCCTTTTUUUURRRREEEE
     While it is not necessary to understand the STIFF file structure to use
     _l_i_b_s_t_i_f_f, this explanation is provided for those who need to know.  A
     Stream TIFF file is first and foremost a valid TIFF file. STIFF is
     derived from the TIFF 6.0 Specification available from Aldus Corporation
     (see below). The terms used below to describe a STIFF file (e.g. IFD) are
     explained in the TIFF specification and will not be described here.

     The primary restriction STIFF places on the TIFF structure is that all
     data must be read from or written to the file without the need to seek
     within the file.  Specifically, within a STIFF file:

     1.   The bitmap image data must be in page number order.

     2.   Data which does not fit in the value section of a tag must be
          located immediately after the IFD and must occur in the same order
          in which the tags are encountered. The exception to this is the
          image data itself, which must come last for each page.

     3.   Image data must immediately follow the IFD and any offset values
          associated with it.

     4.   A terminating, empty IFD will always be added to the end of the
          STIFF file.  This IFD guarantees that an IFD with 0000 in its 'next
          IFD' field will appear in the IFD chain. Note that this empty IFD
          will not be encountered when following IFD pointers if the last
          'real' IFD is written with the 'last' parameter set to 1. While the
          TIFF specification states that IFDs should not be empty, relaxing
          this restriction appears to have no impact on TIFF compatibility.







                                                                        PPPPaaaaggggeeee 3333






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



          A STIFF file can be represented diagrammatically as:

                          _______________________________

                           TIFF header (8 bytes)

                          _______________________________

                           Optional intervening space

                          _______________________________

                           IFD for page 1

                          _______________________________

                           Data for long values in IFD 1

                          _______________________________

                           Image data for page 1

                          _______________________________

                           Optional intervening space

                          _______________________________

                           IFD for page 2

                          _______________________________

                           Data for long values in IFD 2

                          _______________________________

                           Image data for page 2

                          _______________________________

                           ...

                          _______________________________

                           Terminating empty IFD

                          _______________________________
                          ||||||||||||||||||||||||||||||||||||||||||||










































                                                         ||||||||||||||||||||||||||||||||||||||||||||












































     The _l_i_b_s_t_i_f_f functions support only the Motorola (MM) byte ordering. In
     addition to supporting TIFF class B, G and R data, _l_i_b_s_t_i_f_f supports the
     CMYK color image data type (PhotoMetricInterpretation = 5 and InkSet = 1)
     and four additional color image separation types: CMY, YMC, YMCK, and



                                                                        PPPPaaaaggggeeee 4444






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



     KCMY.  For these additional types, PhotoMetricInterpretation = 5, InkSet
     = 2, NumberOfInks = 3 or 4, and the InkNames tag is used to indicate the
     inks contained in each channel.

     When reading an image header, _l_i_b_s_t_i_f_f parses the ink names for these
     additional types, and sets the _t_y_p_e field of the SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure
     to the appropriate value defined in <_s_t_i_f_f._h>.  When writing an image
     header, _l_i_b_s_t_i_f_f writes the appropriate PhotoMetricInterpretation,
     InkSet, NumberOfInks, and InkNames tags based on the value of the _t_y_p_e
     field of the SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure.













































                                                                        PPPPaaaaggggeeee 5555






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



     The CMYK data class is a TIFF data format extension.

             TTTTaaaagggg                         PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
             _________________________________________________________
             BitsPerSample               (1,1,1,1) (4,4,4,4) (8,8,8,8)
             PhotoMetricInterpretation   5
             SamplesPerPixel             4
             PlanarConfiguration         1,2
             NumberOfInks                4

     The CMY data class is a subset of the CMYK class and differs from the
     CMYK class in a TIFF compliant manner.  In the description of the
     SamplesPerPixel tag below, "1 bit planar" refers to the case where
     BitsPerSample has the value (1,1,1,1) and PlanarConfiguration has the
     value 2.

           TTTTaaaagggg                         PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
           _____________________________________________________________
           BitsPerSample               (1,1,1,1) (1,1,1) (4,4,4) (8,8,8)
           PhotoMetricInterpretation   5
           SamplesPerPixel             3 (4 for 1 bit planar)
           PlanarConfiguration         1,2
           NumberOfInks                3

     The YMC data class is a class similar to the CMY class with the exception
     that data is organized as YMC instead of CMY.  When using _l_i_b_s_t_i_f_f, YMC
     data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____YYYYMMMMCCCC.

           TTTTaaaagggg                         PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
           _____________________________________________________________
           BitsPerSample               (1,1,1,1) (1,1,1) (4,4,4) (8,8,8)
           PhotoMetricInterpretation   5
           SamplesPerPixel             3 (4 for 1 bit planar)
           PlanarConfiguration         1,2
           NumberOfInks                3
           InkSet                      2
           InkNames                    yellow,magenta,cyan

     The YMCK class is a class similar to the CMYK class with the exception
     that data is organized as YMCK instead of CMYK.  When using _l_i_b_s_t_i_f_f,
     YMCK data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____YYYYMMMMCCCCKKKK.

             TTTTaaaagggg                         PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
             _________________________________________________________
             BitsPerSample               (1,1,1,1) (4,4,4,4) (8,8,8,8)
             PhotoMetricInterpretation   5
             SamplesPerPixel             4
             PlanarConfiguration         1,2
             NumberOfInks                4
             InkSet                      2





                                                                        PPPPaaaaggggeeee 6666






LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))                      IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                       LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))



             InkNames                    yellow,magenta,cyan,black

     The KCMY class is a class similar to the CMYK class with the exception
     that the data is organized as KCMY instead of CMYK.  When using _l_i_b_s_t_i_f_f,
     KCMY data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____KKKKCCCCMMMMYYYY.

             TTTTaaaagggg                         PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
             _________________________________________________________
             BitsPerSample               (1,1,1,1) (4,4,4,4) (8,8,8,8)
             PhotoMetricInterpretation   5
             SamplesPerPixel             4
             PlanarConfiguration         1,2
             NumberOfInks                4
             InkSet                      2
             InkNames                    black,cyan,magenta,yellow

     Note that for the RGB, CMY, and YMC classes with BitsPerSample values of
     (1,1,1) and a PlanarConfiguration value of 1, pixels are stored two to a
     byte, with the bits ordered from most to least significant. For example,
     CMY data is stored as: CMY0CMY0. Rows are padded to contain an integral
     number of bytes.

     Refer to the header file _s_t_i_f_f._h for additional information regarding the
     STIFF file structure.

PPPPRRRRIIIINNNNTTTTIIIINNNNGGGG SSSSPPPPEEEECCCCIIIIFFFFIIIICCCC SSSSTTTTIIIIFFFFFFFF
     The printing specific functions (PST) provided by _l_i_b_s_t_i_f_f to read and
     write STIFF files as described above. The printing specific aspect of
     these functions is found in the image header structure. The printing
     specific image header (PSTImageHeader) contains all fields of the
     (STImageHeader) plus printing specific information fields such as image
     resolution and halftoning method. If a STIFF stream is written using the
     generic functions and is read using the printing specific functions,
     default values will be used for the PSTImageHeader fields not found in
     the STIFF stream. Similarly, a STIFF stream written using the printing
     specific functions can be read by the generic functions. In this case,
     the additional information in the stream can be ignored or obtained using
     the _S_T_G_e_t_T_a_g function.

     Refer to the header file _p_r_i_n_t_s_t_i_f_f._h for additional information
     regarding printing specific STIFF.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _v_s_t_i_f_f(1), _z_o_o_m_s_t_i_f_f(1).

     _T_I_F_F _6._0 _S_p_e_c_i_f_i_c_a_t_i_o_n - Aldus Corporation, 1992.  For a copy of the TIFF
     6.0 specification contact Aldus Developers Desk, Aldus Corporation, 411
     First Avenue South, Seattle, WA 98104-2871, [phone].







                                                                        PPPPaaaaggggeeee 7777